package bap-main

  1. Overview
  2. Docs

Module Log.Create

generates reporters specialized to the current plugin.

Use include Bap_main_event.Create() to bring to the scope logging and debugging functions.

The functions will post logging events if the corresponding level of debugging is enabled. Right now only BAP_DEBUG and BAP_DEBUG_<plugin> environment variables are consulted to enable/disable the events of the Log.level.Debug level. When neither of these variables is set, the debug function will be a no-op.

Parameters

Signature

val debug : ('a, Format.formatter, unit) format -> 'a

debug "my message: %s" "hello" sends the debugging message.

val info : ('a, Format.formatter, unit) format -> 'a

info "my message: %s" "hello" sends the info message.

val warning : ('a, Format.formatter, unit) format -> 'a

warning "my message: %s" "hello" sends the warning message.

val error : ('a, Format.formatter, unit) format -> 'a

error "my message: %s" "hello" sends the error message.

val report_progress : ?task:string -> ?note:string -> ?stage:int -> ?total:int -> unit -> unit

report_progress ~task:t ~note:n ~state:s ~total:s' () reports a progress of the task t.

Reports that the task t made a progress to the stage s out the total number of stages s'. The note n may provide an additional textual explanation of the current stage. The report doesn't mean that the stage is finished, but rather that it is entered. Thus for s' stages we expect to receive s'-1 reports. (This approach works fine with functional programming and iterating - as in functional programming it is more convenient to report before computation, and during the indexed iteration the index of the last element is one less than the total number of elements).

All parameters are optional, and have the following default values if not specified:

  • parameter task

    defaults to the plugin name;

  • parameter note

    defaults to the empty string;

  • parameter stage

    defaults to None

  • parameter total

    defaults to None or to the last value of this parameter for the given task.

The report_progress bar is an easy way to provide some feedback to the system, either in the form of a progress (if the total number of stages is known) or in the form of a friendly ping back.

The mechanism should be used by analyses that expect to take some time to complete. Usually, one plugin implements only one task, so the task name may be omitted. If an analysis is built from several tasks, then they can be represented as subtasks, and the main task should represent the whole work.

Example:


  let find_interesting_points prog =
    report_progress ~task:"discover" ~total:(Term.length sub_t prog) ();
    Term.enum sub_t prog |> Seq.concat_mapi ~f:(fun stage sub ->
        report_progress ~note:(Sub.name sub) ~task:"discover" ~stage ();
        interesting_points_of_sub sub)

  let check_interesting_points points =
    report_progress ~task:"checking" ~total:(Seq.length points) ();
    Seq.iteri ~f:(fun stage p ->
        report_progress ~note:(Point.name p) ~task:"checking" ~stage ();
        check_point p)
val debug_formatter : Format.formatter

the formatter that could be used to send debug messages.

val info_formatter : Format.formatter

the formatter that could be used to send info messages.

val warning_formatter : Format.formatter

the formatter that could be used to send warnings.

val error_formatter : Format.formatter

the formatter that could be used to send errors