BUDDHA(1)

NAME
buddha - Haskell declarative debugger

SYNOPSIS

buddha [-v] [-h] [-t option] [-d data] [-s phase] [-c level] [file1 ... fileN]

DESCRIPTION

Buddha is a debugger for Haskell 98 programs. To be more precise, it is a declarative debugger. It presents the evaluation of a Haskell program as a series of equivalences, rather than the more traditional stepwise presentation of debuggers for imperative languages.

A typical debugging session involves a number of questions and answers. The questions are posed by the debugger, and the answers are provided by the user. The questions relate to the evaluation of function applications that were made during the execution of the program. Evaluation is presented in a high-level manner, for example, something like:

  Prelude 35 map
     arg 1  = { (True,1) -> 1, (False,2) -> False }
     arg 2  = [(True,1),(False,2)]
     result = [True,False]

This says that the application of map to a function and [(True,1),(False,2)] evaluates to [True,False]. Note how the function (arg 1) is displayed as a (finite) mapping from inputs to outputs. The text `Prelude 35' says that the function was defined on line 35 of the module called Prelude. The job of the user is to determine whether the evaluation of this application is correct in their intended interpretation of the program. Of course, we presume the user knows what their program is supposed to do!

Buddha employs a source-to-source program transformation. The program to be debugged is transformed, compiled, and linked with a debugging library. The transformation rules are crafted in such a way that execution of the transformed program constitutes evaluation of the original (untransformed) program, plus construction of a semantics for that evaluation. The semantics that it produces is a tree with nodes that correspond to equivalences like the one above. Debugging is a traversal of that tree, searching for nodes that do not agree with the user's intention.

The main advantage of this style of debugging is that the user does not need to think about the operational semantics of their program. They only need to think in terms of high-level logical specifications (declarative semantics). This is especially useful in non-strict languages like Haskell, where the evaluation order of the program is very difficult to relate to the structure of the source code (even experts find the operational behaviour of their program hard to understand).

There are two steps to use buddha:

1.  You must transform your program and compile the result. This step is achieved by running buddha in the directory that contains your code. This will create a sub-directory called Buddha. When buddha is complete it will have built a new program called debug which will be placed in the Buddha sub-directory.

2.  After the first step is complete, you must execute the new program called debug. This will behave just like the original program. This includes accepting the same command line arguments. Debugging does not begin until all the computation of the original program is done. At that point the debugging algorithm will start. You will be presented with a prompt and debugging proceeds as an interactive session. You can make judgements about the correctness of function applications. Or you can browse around the call-graph of the program. You can also print pretty representations of the call-graph or values involved in the computation. These representations are written to file using the dot graph language.

This manual entry only deals with the first of the above stages. Use of the interactive debugging environment is described in the buddha user's guide which can be found on the buddha homepage.

In many circumstances you can just run buddha as it is without any command line arguments. If you call it without any arguments it will just transform all of the Haskell source files in the current directory.

If you only want to transform a subset of the Haskell files in the current directory then you must list them all explicitly.

If you want to give different options to different modules then you can transform each module one at at time (by naming the module that you want explicitly). However, you must be careful to transform them in dependency order. For example, if module A depends on module B (A imports B), then you must transform B before A. When you ask buddha to transform multiple modules at once it will automatically figure out the dependencies for you so you can list them in any order.

If you make changes to your program in between debugging sessions then you will have to re-run the transformation again.

OPTIONS

[-h]
     Show help information about using buddha.

[-v]
     Show version information.

[-t option]
     Alter the behaviour of the transformation. The parameter option tells buddha to do special things when transforming a module. The current available options are:

    *   cheapHo: cheap higher-order functions. Higher-order values (functions passed as arguments to other functions, or returned as results) are recorded by buddha. This recording consumes memory and prevents garbage collection of the values referred to by the higher-order values. In many circumstances you don't want to see these higher-order values --- they may be encapsulated in trusted code. In these circumstances you can use this option to prevent the recording of those values, thus saving memory.

    *   noprelude: don't implicitly import the Prelude when transforming a module. This is similar to the -fno-implicit-prelude option of GHC. Essentially it does not add an import Prelude to the module before transforming. This is necessary when transforming the Prelude itself (because the Prelude does not import the Prelude!). The default behaviour is to implicitly import the prelude for all modules that do not explicitly import it --- this is usual Haskell 98 behaviour.

[-d data]
     Dump information about the transformation in progress. The parameter data is a string that identifies some internal data that buddha manipulates. Sometimes it is useful to see this information, mostly when debugging buddha itself. The current available dumps are:

    *   parse: syntax tree after the module is parsed.

    *   idents: information about all the top-level identifiers in the program (their arity, binding style etc).

    *   rename: source code after the module is renamed.

    *   derives: automatically derived class instance declarations.

    *   desugar: module after desugaring has been performed, the result should be a valid Haskell program.

    *   imports: items that are imported from other modules.

    *   assocs: associations between types and data constructors and classes and class members --- this is used for expanding the (..) notation in import and export declarations.

    *   infix: fixity information for all top-level variables and constructors that are in scope.

    *   synonyms: all the type synonyms that are in scope.

    *   transOpts: all the transformation options found in *.opt.

    *   stats: statistics about the whole program, such as counts of saturated and unsaturated function applications.

    *   statsByModule: print statistics about the code on a per-module basis.

    *   all: all of the above.

    Dumping this information does not interrupt the transformation in any way.

[-s phase]
     Skips a particular phase in the processing of files. There are four phases to the processing of files, each phase can be skipped. The phases are:

    *   init: initialisation. Before transforming any files buddha creates a directory called Buddha and places some important files in there (actually it only does this if it hasn't already been done before).

    *   depend: dependency analysis. When transforming more than one file buddha must calculate the dependencies amongst them. It writes the dependencies into a file called depend which gets places in the directory called Buddha.

    *   trans: transformation proper. Each file is transformed by buddha. For example Foo.hs becomes Buddha/Foo_B.hs.

    *   build: building the debugging version of the program. After transformation buddha builds a program called Buddha/debug which is the debugging version of your program - the thing that you run to debug.

[-c level]
     Diagnostics about what buddha is doing. This determines how much information buddha reports as it is processing your files. There are three levels of output, indicated by the parameter level:

    *   silent: don't print anything other than the absolutely necessary (error messages and the like).

    *   normal: print a small amount of information, mostly just a short message about the current stage that it is up to. Just to let you know that it is still running. This is the default level.

    *   verbose: print a lot of detail about everything that is happening. This is normally only useful if something doesn't appear to be working as it should.

EXAMPLES

Suppose you have three Haskell files that make up your program, and they are called Main.hs, A.hs and B.hs. Suppose also that Main imports A, and A imports B.

You can just transform all the modules at once with the command:
   buddha

Perhaps you want cheap higher-order functions in module A, but you want the default transformation in module's Main and B:
   buddha B.hs
   buddha -t cheapHo A.hs
   buddha Main.hs
Notice how the modules must be transformed in dependency order. This is only necessary in this case because we wanted to use a different option for A.hs.

If there are more Haskell files in your directory and you don't want to transform them, then you must list the ones you want to transform explicitly:
   buddha Main.hs B.hs A.hs
Note that it doesn't matter in what order you list them, buddha will figure out their dependencies automatically.

REQUIREMENTS

ghc ghc version >= 6. Note that you must also have ghc's libraries compiled for profiling. Consult the ghc documentation to see how this is obtained.

readline
    The interactive debugging environment uses readline. Normally, you will want to have readline for ghc anyway.

SEE ALSO

ghc(1)

LICENSE AND COPYRIGHT

Copyright
    (C)2004, Bernie Pope, Melbourne, Australia bjpop@cs.mu.oz.au

License
    This program can be redistributed and/or modified under the terms of GNU GPL. You can find the terms of the license on the GNU web page: http://www.gnu.org

AUTHOR

Bernie Pope
Email: bjpop@cs.mu.oz.au
WWW: http://www.cs.mu.oz.au/~bjpop/buddha.