Module Std.Self

A self reflection.

This is a generative functor module refers to an information bundled with an application. Use include Self() syntax to bring this definitions to the scope.

It is designed to be used inside a plugin, but can be used in a standalone program as well (this is useful, for debugging plugins, by running them as a standalone applications).

If run in a standalone mode, then field name would be set to Sys.executable_name and argv to Sys.argv.

Note: this module uses the Event.Self() module and extends it with several more fields, such as name, version, doc, and argv. It is recommended to use Event.Self() aka Bap_main_event.Self() instead.

Parameters

Signature

val name : string

name of a plugin

val version : string

version number

val doc : string

A short, one-line description

val argv : string array

args name returns an array of arguments designated for a plugin with a given name.

The arguments will be extracted from Sys.argv array by removing all arguments that doesn't start with --name-. Then, from all command arguments that are left, the --name- prefix is substituted with --. For example, if argv contained [| "bap"; "-lcallgraph"; "--callgraph" "--callgraph-help"|] then pass that registered itself under callgraph name will receive the following array of arguments [| "callgraph"; --help |] . That means, that plugins can't accept arguments that are anonymous or short options

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

debug fmt ... send a debug message

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

info fmt ... send an info message

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

warning fmt ... send a warning message

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

error fmt ... send an error message

val debug_formatter : Stdlib.Format.formatter

formatter that sends debug messages

val info_formatter : Stdlib.Format.formatter

formatter that sends info messages

val warning_formatter : Stdlib.Format.formatter

formatter that sends warning messages

val error_formatter : Stdlib.Format.formatter

formatter that sends error messages

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)
module Config : sig ... end

This module allows plugins to access BAP configuration variables.