Getting started with Morphine

Setting up the Unix environment

The current version of Morphine  runs with a Mercury release of the day later than April 99⁴. Currently, it has been tested on sparc-sun/Solaris 2.{5,6,7} and on pc-i686/Linux-2.0.34, but it should work on any other unix systems. It requires the ECLiPSe⁵ Prolog system; it has been tested with ECLiPSe 4.1 and later.

Building your Mercury compiler

To be able to run Mercury programs under the control of Morphine, you need to compile your Mercury program as for mdb, the internal Mercury debugger. There are basically two methods:

1.

mmc --trace <trace_option> <program_name>

where <trace_option> can be none, shallow, deep or default.

Example:

    mmc --trace deep hello.m

2.

mmc --grade <debug_grade> <program_name> or
mmc -s <debug_grade> <program_name>

where <debug_grade> is a grade that includes the word debug.

Example: if your Mercury compiler has been built in the asm_fast.gc.tr.debug grade:

    mmc -s asm_fast.gc.tr.debug hello.m

or

    mmake hello.depend 
    mmake -s asm_fast.gc.tr.debug hello.m

For more details about preparing a program for debugging, please refer to:
http://www.cs.mu.oz.au/research/mercury/information/doc/user_guide_7.html, section ``Preparing a program for debugging''.

Starting an Morphine session

In your working window type ``Morphine''; you enter Eclipse extended by the Morphine libraries. Note that you can use it as a simple Prolog session.

...
Loading /home/swann/d01/lande/jahier/.morphine-rc...
ECLiPSe Constraint Logic Programming System [kernel]
Version 4.1.0, Copyright IC-Parc and ICL, Sun Feb 21 18:37 1999
[Morphine]:

To run the Mercury program hello (that you can find in the ``sample'' directory of your Mercury distribution), use the command run/1.

[Morphine]: run(hello)
 1: 1 [1] CALL main(state('<<c_pointer>>'), -)

A complete example session can be found in Section 4.

Note that to quit an Eclipse session, you need to type ^d.

   
A first try with Morphine

You can start to enter debugging commands in the Morphine session.

We recommend to start with the step_by_step_M  scenario, and in particular with the following commands to trace the program execution (the abbreviations of the commands are given in curly braces):

print_event {p} print the current trace event.
next {n} print the following trace event.  

  Next, you can try a simple mechanism which provides you with the facilities to trace a part of the execution, and to stop on a certain trace event. This mechanism is called trace-till-condition . It is based on the fact that those commands which can be used to move forwards in the trace (like next) are backtrackable. They can be used in the following way:

    [Morphine]: next, <condition>.

This debugging goal will cause Morphine to print the following trace events, until the condition is fulfilled. The condition can be any Prolog goal. In order to specify a condition depending on the values of the trace events (see section 2.2), you can use the current command which is described in the Reference Manual (Part II). Try for example:

    [Morphine]: next, current(port = exit).

Note that unification can help to specify precisely when the condition shall succeed. For example, if you want to trace until predicate permutation/2  is called and where the first argument is a list of length 2, you can use the following Morphine goal:

    [Morphine]: next, current(proc = permutation/2 and arg = [[A1,A2], _]).

 

If you want to skip a part of the trace, and to specify more precisely which trace events you actually want to see, this can be achieved by using the skip-till-condition  mechanism. It is based on a set of primitives which enable moving forwards in the trace like the commands listed above, but without actually printing any trace event (indicated by the ending _np = ``no print''):

next_np {n_np} move forwards to the next trace event.  

In order to skip a part of the trace till a certain condition is fulfilled, you can enter for example

    [Morphine]: next_np, 
       current(proc = sort/2 and port = exit and arg = [-, List]),
       length(List, Length),
       Length > 7,
       print_event.

This will repeat to move forwards to the next trace event without printing it, until the condition is true, and then print the current trace event. Here, the condition is that the second argument of procedure sort/2 should be a list of length greater than 7 at exit ports. Note the use of the -ïn the arguments list that avoids us to retrieve the first argument as we do not need it; retrieve arguments one by one may be useful if some unused arguments are very big.

The sophisticated command of Morphine is fget/1; it filters efficiently through execution traces. Section 4 illustrates in depth how to use it and the Reference manual (Part II page ) describes it.

Getting some help

You can use the on-line help in scenario help  to get a survey of the other debugging strategies provided by Morphine. Start by calling command help/0  which will tell you how to use the on-line help and will list the different commands of the help scenario. You can get some help on the Morphine commands, primitives and procedures thanks to man/1 command and get some help on the ECLiPSe specific commands with help/1. Note that you can use the commands and primitives of all the scenarios visible in the current module. The scenario paradigm is only a virtual structure which does not restrict you to the use of one scenario at a time.