Debug.Hoed.Stk

Hoed.Stk is a tracer and debugger for the programming language Haskell. You can trace a program by annotating functions in suspected modules and linking your program against standard profiling libraries.

Hoed.Pure is recommended over Hoed.Stk because to debug your program with Hoed.Pure you can optimize your program and do not need to enable profiling.

After running the program a computation tree is constructed and displayed in a web browser. You can freely browse this tree to get a better understanding of your program. If your program misbehaves, you can judge the computation statements in the tree as right or wrong according to your intention. When enough statements are judged the debugger tells you the location of the fault in your code.

I work on this debugger in the context of my Ph.D. research. Read more about the theory behind Hoed at http://maartenfaddegon.nl/#pub.

To use Hoed on your own program, annotate your program as described below. For best results profiling is enabled and optimization disabled. If you use cabal to build your project, this is be done with:

cabal configure --disable-optimization --enable-profiling

I am keen to hear about your experience with Hoed: where did you find it useful and where would you like to see improvement? You can send me an e-mail at [e-mail], or use the github issue tracker https://github.com/MaartenFaddegon/hoed/issues.

Basic annotations

observe :: Observable a => String -> a -> a

Functions which you suspect of misbehaving are annotated with observe and should have a cost centre set. The name of the function, the label of the cost centre and the label given to observe need to be the same.

Consider the following function:

triple x = x + x

This function is annotated as follows:

triple y = (observe "triple" (\x -> {# SCC "triple" #}  x + x)) y

To produce computation statements like:

triple 3 = 6

To observe a value its type needs to be of class Observable. We provided instances for many types already. If you have defined your own type, and want to observe a function that takes a value of this type as argument or returns a value of this type, an Observable instance can be derived as follows:

  data MyType = MyNumber Int | MyName String deriving Generic

  instance Observable MyType

runO :: IO a -> IO ()

The main entry point; run some IO code, and debug inside it. After the IO action is completed, an algorithmic debugging session is started at http://localhost:10000/ to which you can connect with your webbrowser.

For example:

  main = runO $ do print (triple 3)
                   print (triple 2)

printO :: Show a => a -> IO ()

Short for runO . print.

Experimental annotations

observeTempl :: String -> Q Exp

observedTypes :: String -> [Q Type] -> Q [Dec]

observeCC :: Observable a => String -> a -> a

observe' :: Observable a => String -> Identifier -> a -> (a, Int)

data Identifier

Constructors

UnknownId

DependsJustOn Int

InSequenceAfter Int

Instances

Eq Identifier

Ord Identifier

Show Identifier

(*>>=) :: Monad m => m a -> (Identifier -> (a -> m b, Int)) -> (m b, Identifier)

(>>==) :: Monad m => (m a, Identifier) -> (Identifier -> (a -> m b, Int)) -> (m b, Identifier)

(>>=*) :: Monad m => (m a, Identifier) -> (Identifier -> (a -> m b, Int)) -> m b

logO :: FilePath -> IO a -> IO ()

The Observable class

newtype Observer

Constructors

O (forall a. Observable a => String -> a -> a)

class Observable a where

Minimal complete definition

Nothing

Methods

observer :: a -> Parent -> a

Instances

Observable Bool

Observable Char

Observable Double

Observable Float

Observable Int

Observable Integer

Observable ()

Observable Dynamic

Observable SomeException

Observable a => Observable [a]

Observable a => Observable (IO a)

Observable a => Observable (Maybe a)

(Observable a, Observable b) => Observable (a -> b)

(Observable a, Observable b) => Observable (Either a b)

(Observable a, Observable b) => Observable (a, b)

(Ix a, Observable a, Observable b) => Observable (Array a b)

(Observable a, Observable b, Observable c) => Observable (a, b, c)

(Observable a, Observable b, Observable c, Observable d) => Observable (a, b, c, d)

(Observable a, Observable b, Observable c, Observable d, Observable e) => Observable (a, b, c, d, e)

(<<) :: Observable a => ObserverM (a -> b) -> a -> ObserverM b infixl 9

thunk :: (a -> Parent -> a) -> a -> ObserverM a

nothunk :: a -> ObserverM a

send :: String -> ObserverM a -> Parent -> a

observeBase :: Show a => a -> Parent -> a

observeOpaque :: String -> a -> Parent -> a

debugO :: IO a -> IO [Event]

run some code and return the CDS structure (for when you want to write your own debugger).

data CDS

Instances

Eq CDS

Ord CDS

Show CDS

class Generic a

Representable types of kind *. This class is derivable in GHC with the DeriveGeneric flag on.

Minimal complete definition

from, to

Instances

Generic Bool

Generic Char

Generic Double

Generic Float

Generic Int

Generic Ordering

Generic ()

Generic All

Generic Any

Generic Arity

Generic Fixity

Generic Associativity

Generic WindowBits

Generic Format

Generic Method

Generic CompressionLevel

Generic MemoryLevel

Generic CompressionStrategy

Generic [a]

Generic (U1 p)

Generic (Par1 p)

Generic (Maybe a)

Generic (ZipList a)

Generic (Dual a)

Generic (Endo a)

Generic (Sum a)

Generic (Product a)

Generic (First a)

Generic (Last a)

Generic (Either a b)

Generic (Rec1 f p)

Generic (a, b)

Generic (Const a b)

Generic (WrappedMonad m a)

Generic (Proxy * t)

Generic (K1 i c p)

Generic ((:+:) f g p)

Generic ((:*:) f g p)

Generic ((:.:) f g p)

Generic (a, b, c)

Generic (WrappedArrow a b c)

Generic (M1 i c f p)

Generic (a, b, c, d)

Generic (a, b, c, d, e)

Generic (a, b, c, d, e, f)

Generic (a, b, c, d, e, f, g)