The Hoed package

[Tags:bsd3, library]

Hoed 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.

To locate a defect with Hoed you annotate suspected functions and compile as usual. Then you run your program, information about the annotated functions is collected. Finally you connect to a debugging session using a webbrowser.

Hoed comes in two flavours: Hoed.Pure and Hoed.Stk. Hoed.Pure is recommended over Hoed.Stk: to debug your program with Hoed.Pure you can optimize your program and do not need to enable profiling. Hoed.Stk is Hoed as presented on PLDI 2015 and possibly has benefits over Hoed.Pure for debugging concurrent/parallel programs.


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.1.0.1, 0.2.0, 0.2.1, 0.2.2, 0.3.0, 0.3.1, 0.3.2, 0.3.3, 0.3.4, 0.3.5, 0.3.6
Change log changelog
Dependencies array, base (==4.*), containers, deepseq, directory, extensible-exceptions, filepath, FPretty, Hoed, lazysmallcheck, libgraph (==1.9), mtl, network, process, QuickCheck, random, RBTree (==0.0.5), regex-posix, template-haskell, threepenny-gui (==0.6.*), unix, utf8-string, X11 (>=1.5 && <1.7) [details]
License BSD3
Copyright (c) 2000 Andy Gill, (c) 2010 University of Kansas, (c) 2013-2015 Maarten Faddegon
Author Maarten Faddegon
Maintainer hoed@maartenfaddegon.nl
Category Debug, Trace
Home page http://maartenfaddegon.nl
Source repository head: git clone git://github.com/MaartenFaddegon/Hoed.git
Uploaded Sun Dec 6 13:24:10 UTC 2015 by faddegon
Distributions NixOS:0.3.6
Downloads 1621 total (44 in the last 30 days)
Votes
0 []
Status Docs not available [build log]
Last success reported on 2015-12-06 [all 3 reports]
Hackage Matrix CI

Modules

  • Debug
    • Hoed
      • Debug.Hoed.Pure
      • Debug.Hoed.Stk

Flags

NameDescriptionDefaultType
buildexamples

Build example executables.

DisabledAutomatic
validatepure

Build test cases to validate Hoed-pure.

DisabledAutomatic
validatestk

Build test cases to validate Hoed-stk.

DisabledAutomatic
validategeneric

Build test cases to validate deriving Observable for Generic types.

DisabledAutomatic
validateprop

Build test cases to validate deriving judgements with properties.

DisabledAutomatic

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Readme for Hoed

Readme for Hoed-0.3.2

Hoed - A Lightweight Haskell Tracer and Debugger Build Status

Hoed is a tracer and debugger for the programming language Haskell.

Using Hoed

To locate a defect with Hoed you annotate suspected functions and compile as usual. Then you run your program, information about the annotated functions is collected. Finally you connect to a debugging session using a webbrowser.

Let us consider the following program, a defective implementation of a parity function with a test property.

isOdd :: Int -> Bool
isOdd n = isEven (plusOne n)

isEven :: Int -> Bool
isEven n = mod2 n == 0

plusOne :: Int -> Int
plusOne n = n + 1

mod2 :: Int -> Int
mod2 n = div n 2

prop_isOdd :: Int -> Bool
prop_isOdd x = isOdd (2*x+1)

main :: IO ()
main = printO (prop_isOdd 1)

main :: IO ()
main = quickcheck prop_isOdd

Using the property-based test tool QuickCheck we find the counter example 1 for our property.

./MyProgram
*** Failed! Falsifiable (after 1 test): 1

Hoed can help us determine which function is defective. We annotate the functions isOdd, isEven, plusOne and mod2 as follows:

import Debug.Hoed.Pure

isOdd :: Int -> Bool
isOdd = observe "isOdd" isOdd'
isOdd' n = isEven (plusOne n)

isEven :: Int -> Bool
isEven = observe "isEven" isEven'
isEven' n = mod2 n == 0

plusOne :: Int -> Int
plusOne = observe "plusOne" plusOne'
plusOne' n = n + 1

mod2 :: Int -> Int
mod2 = observe "mod2" mod2'
mod2' n = div n 2

prop_isOdd :: Int -> Bool
prop_isOdd x = isOdd (2*x+1)

main :: IO ()
main = printO (prop_isOdd 1)

After running the program a computation tree is constructed and displayed in a web browser.

./MyProgram
False
Listening on http://127.0.0.1:10000/

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.

Screenshot of Hoed

Installation

Hoed is available from Hackage and can be installed with Cabal.

cabal install Hoed

Other Tracers

Many of the ideas for Hoed come from the Hat project. Hoed is the Dutch word for a hat. Compared to Hoed, Hat can give more detailed traces. However, Hat requires all modules to be transformed and is therefore not practical for many real-world Haskell programs.

The idea to observe values with local annotations comes from the HOOD project. Unlike Hoed, HOOD does not give relations between observed values. HOOD also requires the programmer to write a class-instance for the type of the value they want to observe. With Hoed these instates can be derived automatically.