Introduction to MetaPRL Debugging

First, before you start debugging your code, it may be a good idea to make sure you are using the "verbose" refiner.

In the process of debugging your code, you may end up adding some statements that print some debugging information or perform some sanity checks (and notify you if something went wrong). Usually you would want some way of temporarily enabling and disabling such debugging code. Of course, you can always comment it out when you do not need it and uncomment it back when you need it again. But instead of this playing with comments, please consider using the Mp_debug module.

Add the following to your code:

• At the beginning of the file:

  open Printf
  open Mp_debug
  open Refiner.Refiner.Term
  
  let debug_<name> =
     create_debug (**)
        { debug_name = "<name>";
          debug_description = "Some description of what is debugged by it";
          debug_value = false
        }

  This will create an object of type bool ref that you can use to switch the debugging code on and off:
• In the code you want to debug you add, for example:

    if !debug_<name> then begin
        some_debugging_code...;
        eprintf "Integer i is %d and term t is %a%t" i print_term t eflush;
     end;

  It is important that you do not forget to flush the output, otherwise if you code later crashes or raises an exception, you may never see it.

By default, the !debug_<name> would be false. There are several ways to make it true:

1. By setting the MP_DEBUG environment variable in your shell before you start MetaPRL. MP_DEBUG should be a colon-separated list of names (without the debug_ prefix).
2. By running the "set_debug "<name>" true" command from the MetaPRL toploop.
3. By using debug_value = true instead of false in create_debug. Usually, it's not a good idea to do so, unless you want all MetaPRL users to participate in the debugging.
4. By using debug_<name>:=true in your code. It is rarely a good idea, but here is an example when it may be a good idea to use it:

      if !debug_my_code then begin
         let save=!debug_other_code in
         debug_other_code:=true;
         other_code ();
         debug_other_code:=save
      end else
         other_code () 

   Note that whoever wrote the other_code does not have to export debug_other_code in their .mli file - see Note 1.

Notes

1. If you run create_debug more that once with the same debug_name (for example, in several modules or in several instances of the same module), you'll get the pointer to the same boolean. If you are sure that the debug with that name is already created, you can use a shorter load_debug "<name>" instead of create_debug { ... } to get a reference to that debug variable.
2. If you are creating lots of debugging code, you may want to create several debug variables with different names to have finer control over what pieces of debugging code are active.

Debug variables

• address: show term addressing operations
• alpha_equal: display alpha equality operations
• arith: display arith operations
• ascii_io: report ASCII IO errors verbosely
• auto: Display auto tactic operations
• cache: Show TPTP cache operations
• convert: show proof format conversions
• conv: display conversion operation
• czf_set: display czf_set operations
• dform: show display form formatting
• dtactic: display dT tactic operations
• edit: show editing commands
• ensemble: Display MP Ensemble Application actions
• eqcd: display eqcd operations
• file_base: display file operations on logic files
• filter_cache: display cache operations during compiling
• filter_parse: display compiling operations
• filter_path: display path expansions
• filter_prog: display operations that convert ML to terms
• free_vars: Display free variables calculation
• grammar: display term parsing operations
• http: HTTP server operations
• inet: Display internet socket operations
• jprover: Display Jprover operations
• load: Print file and rule names as they are loaded and initialized
• lock: show locking operations
• match: print term on proof copying errors
• memo: Display memo operations
• message: Display Ensemble messages
• ocaml: debug ocaml term parsing
• opname: display opname construction
• outboard: Ensemble outboard operations
• package_info: display package operations
• pipe: Debug shared memory pipe operations
• proof_normalize: show proof normalization
• proof_pending: show proof Pending operations
• proof: show proof operations
• prop_decide: show propDecide operations
• queue: Remote queue operations
• queue: Show remote queue operations
• reduce: display reductions
• refine: Display refinement operations
• remote: Show remote process management
• resource: display resource operations
• rewrites: Display rewrite applications
• rewrite: Term rewriting operations
• rformat: display text formatting operations
• schedule: Show thread scheduling
• sentinal: Display sentinal operations
• share: Display MP Ensemble Application memory sharing
• shell: Display shell operations
• simple_print: show simple printing operations
• spell: check spelling
• strategy: Show tactic strategy
• string: check string bounds
• subst_ds: display term_ds substitution operations
• subst: Substition operations
• subst: Substitution operations
• summary: display prl summary operations
• sync: Show event synchronization
• tactic: display primitive tactic operations
• terminal: show terminal size operations
• term_table: Display Term_table (term hashtable) operations
• tptp_prove: show TPTP proof steps
• tptp: show TPTP tactic operations
• unjustified: show how Unjustified nodes are created